Novell 
DirXML. Driver for Delimited 


Text 


lead O 
| IMPLEMENTATION GUIDE 


August 3, 2004 


Novell. 


Legal Notices 


Novell, Inc. makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express 
or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to revise this publication and to 
make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. 


Further, Novell, Inc. makes no representations or warranties with respect to any software, and specifically disclaims any express or implied warranties 
of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to make changes to any and all parts of Novell software, 
at any time, without any obligation to notify any person or entity of such changes. 


You may not export or re-export this product in violation of any applicable laws or regulations including, without limitation, U.S. export regulations 
or the laws of the country in which you reside. 


Copyright O 2004 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or 
transmitted without the express written consent of the publisher. 


Patents Pending. 


Novell, Inc. 

404 Wyman Street, Suite 500 
Waltham, MA 02451 

U.S.A. 


www.novell.com 


DirXML Driver for Delimited Text Implementation Guide 
August 3, 2004 


Online Documentation: To access the online documentation for this and other Novell products, and to get updates, see 
www.novell.com/documentation. 


Novell Trademarks 


DirXML is a registered trademark of Novell, Inc. in the United States and other countries. 

eDirectory is a trademark of Novell, Inc. 

NDS is a registered trademark of Novell, Inc., in the United States and other countries. 

NetWare is a registered trademark of Novell, Inc., in the United States and other countries. 

Novell is a registered trademark of Novell, Inc., in the United States and other countries. 

Novell Client is a trademark of Novell, Inc. 

Novell Directory Services is a registered trademark of Novell, Inc., in the United States and other countries. 
Nsure is a trademark of Novell, Inc. 

SUSE is a registered trademark of SUSE LINUX AG, a Novell company. 

ZENworks is a trademark of Novell, Inc. 


Third-Party Trademarks 


All third-party trademarks are the property of their respective owners. 


Contents 


About This Guide 7 

1 Introducing the DirXML Driver for Delimited Text 9 
OVErVIEW Aa a A FE AA E A R E E een E SE Ge 9 

Four Java Interfaces to the Driver ........... eee ren 9 
Driver Heartbeat. y x h e både Hd AA bee A A is ae TT SE ee 10 
Default Driver Configuration ~. < o «s-e usos ca kaca RRR aee aoe ka RRR RRR RR RE 10 

Data Flow. BE A A A SEL Save A AAA E A 10 
Supported File Types. . . naoa a a 12 

2 Installing the DirXML Driver for Delimited Text 15 
Where to Install the Driver eosa. sa oca e T tr 2 EG a EM eh RA KATE BO e 15 
Preréquistes:u us arr T oe te at a a oh R DN ae Ee TEE EE de di 15 
Installing the Driver . ++ 2 kv «ee Se at e deg er TA GE a Ge EEG rer GÅ GE a Bae DER 15 
Installingto0 WVINOWS: + ++ Ge karpe Gude GE AG GNR be Gb Re Aae Ge EDEN wap pie ee 15 
Installing to NetWare... va sjaa o Von RV ee GR e SE AEE år Ge 17 
Installing:to'Linux: or Solaris: 3 + åå same oe SR ee UTE Se Mr DE Sr KØ Gå 18 
Setting.Upithe DNverus 4 å a A SJ Fisk De ET Sete de A sa Serie i 21 
Configuring the Driver. 4 43 ve AGODA ØSE KASTER GE Ge AN GE Aa El KE Ge e ka å 21 
Prepåring:Datå Locations: exotica aa GLE Ev Sake Få ES Fe Em ok dee 23 

Starting the Driver: r a a ta Mads DE SA SEEGER EEE Sb SEE STE EG kime 23 
Migrating and Resynchronizing Data . .............. kr kr kran 23 
Activating the: Driver: ja x bm Gu seat Gå å ANE fs Å akk sen ek Aae Sah slett 25 

3 Upgrading the DirXML Driver for Delimited Text 27 
4 Customizing the DirXML Driver for Delimited Text 29 
Configuring Driver Parameters. . 2 ce he ee ee 29 
Driver Settings’ t iher dear obo e tt ea Se A eed Gard od Li et 31 
Subscriber SettingS voor a Sa pe ee be a ae ee Pa ew bee ee ba ee te 32 
Publisher Settings: så net ka ee oe Se E ES ks Cha e PO Os Pew Så LE KA SG G RSS 34 

Setting Up One-Way Synchronization . .. oaoa aaa eee ka 35 
Configuring for XDS XML Files . ................. eee eee eee kue 36 
Configuring Data Synchronization . . . . ooa oaa 37 
Using Java Interfaces to Customize File Processing. . . 2.222 aa a a a 38 
Creating a New Java Class. ........... a 38 
Greéating'å Java gar Files s Z ee ae do Bere ee da EA sete dd SSE SD ed 38 
Configuring the Driver to Use the New Class... 2... eee eee eee ran 38 

A Documentation Updates 41 
August 3,2004 SD Ma a TET ee ee EA a are eae ask a 41 


Contents 5 


6 DirXML Driver for Delimited Text Implementation Guide 


About This Guide 


This guide explains how to install and configure the DirXML® Driver for Delimited Text. 
The guide contains the following sections: 

+ Chapter 1, “Introducing the DirXML Driver for Delimited Text,” on page 9 

+ Chapter 2, “Installing the DirXML Driver for Delimited Text,” on page 15 

+ Chapter 3, “Upgrading the DirXML Driver for Delimited Text,” on page 27 

+ Chapter 4, “Customizing the DirXML Driver for Delimited Text,” on page 29 

+ Appendix A, “Documentation Updates,” on page 41 
Additional Documentation 


For information on Nsure™ Identity Manager, see the Identity Manager Documentation Web site 
(http://www.novell.com/documentation/lg/dirxm120/index.html). 


For information on other DirXML drivers, see Driver Implementation Guides (http:// 
www.novell.com/documentation/lg/dirxmldrivers/index.html). 


Documentation Updates 


For the most recent version of this document, see DirXML Driver for Delimited Text in the Driver 
Implementation Guides (http://www.novell.com/documentation/lg/dirxmldrivers/index.html) 
section. 


Documentation Conventions 


In this documentation, a greater-than symbol (>) is used to separate actions within a step and items 
within a cross-reference path. 


A trademark symbol a TM, etc.) denotes a Novell trademark. An asterisk (*) denotes a third-party 
trademark. 


User Comments 


We want to hear your comments and suggestions about this manual and the other documentation 
included with Novell DirXML. Send e-mail to proddoc@novell.com. 
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Overview 


Introducing the DirXML Driver for Delimited Text 


This section covers the following topics: 
+ “Overview” on page 9 
+ "Four Java Interfaces to the Driver” on page 9 
+ "Driver Heartbeat” on page 10 
+ "Default Driver Configuration” on page 10 


For information on new features in Nsure™ Identity Manager, see “What's New in Identity 
Manager 2?” in the Novell Nsure Identity Manager 2 Administration Guide. 


The DirXML? Driver for Delimited Text is designed to synchronize user data between Novell? 
eDirectory™ and XML files or delimited text files that contain comma-separated values. 


This driver differs from other DirXML drivers in that it does not interface directly with any 
particular application. Text files take the place of the application. 


Using your own style sheets, you can enable the driver to work with virtually any text-based file 
that contains predictably repeatable patterns. 


Four Java Interfaces to the Driver 


The Driver for Delimited Text includes four Java* interfaces: 
+ InputSorter 
+ InputSource 
+ PreProcessor 


+ PostProcessor. 


These interfaces enable you to add extensions, which are optional. The driver continues to function 
as before without extensions. However, if you want to directly modify the behavior of the driver, 
but have been unable to make these modifications from a style sheet or DirXML script, extending 
the Driver for Delimited Text can be useful. 


By using Java classes that you write, you can use the interfaces to customize the publish and 
subscribe processes in the following ways: 
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Process Interface Description 


Publish InputSorter Defines the processing order of multiple input file. 


The system where your driver is installed determines the default 
processing order. For example, files on an NT system are 
processed in alphabetical order. You can use the InputSorter to 
impose the processing order that you require. 


Publish InputSource Provides data other than the files in the default location for the 
driver to process. 


For example, you could check an FTP server for input files and 
then transfer the files to the local file system for processing. 


Publish PreProcessor Ties data manipulation required to prepare input files for driver 
processing directly to the driver. 


Before this interface was available, preprocessing was 
independent of the driver. You could create a separate 
application that would monitor another directory for input files, 
modify the files in some way, and then copy the files to the input 
directory of the driver. By creating a class that implements the 
PreProcessor, you can do this type of preprocessing more 
directly. 


Subscribe PostProcessor Ties data manipulation required by the application consuming 
eDirectory output directly to the driver. 


These enhancements to the driver require Java programming. For more information, see "Using 
Java Interfaces to Customize File Processing” on page 38. 


Driver Heartbeat 


The DirXML engine accepts heartbeat documents from the Driver for Delimited Text. You can 
configure the driver to send the documents. 


Default Driver Configuration 


This section provides information on the following: 
+ “Data Flow” on page 10 
+ “Supported File Types” on page 12 


For information on Identity Manager fundamentals, see the Nsure Identity Manager 
Administration Guide (http://www.novell.com/documentation/lg/dirxml20/1ndex.html). 


Data Flow 


Publisher and Subscriber Channels 


The Driver for Delimited Text supports Publisher and Subscriber channels: 


+ The Publisher reads information from input text files on your local file system and submits 
that information to eDirectory via the DirXML engine. 
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Policies 


By default, the Publisher does the following: 


1. Checks the input directory every 10 seconds. 

2. Processes any files that have a .csv extension. 

3. Changes .csv extensions of processed files to .bak. 
4. Cycles through this process until you stop the driver. 


+ The Subscriber watches for additions and modifications to eDirectory objects and creates 
output files on your local file system that reflect those changes. 


By default, the Subscriber keeps an output file open until either 200 transactions have been 
logged or 30 seconds have elapsed. When either of these thresholds is reached, the output file 
is saved with a number.csv filename and a new output file is opened. 


The sample configuration that ships with this driver includes both Subscriber and Publisher 
channels. However, in many configurations, only one-way data flow is required. In those 
configurations, only a Publisher or Subscriber channel is used. The other channel is disabled. 


Policies are used to control data synchronization between the driver and eDirectory. The Driver for 
Delimited Text comes with the set of preconfigured policies detailed in the following table. You 
can customize these policies by using Novell iManager, as explained in Chapter 4, “Customizing 
the DirXML Driver for Delimited Text,” on page 29, 


Policy Description 
Schema Map Configured on the driver object. 


Maps eDirectory User properties to application attributes as follows: 
Surname > LastName 
Given Name > FirstName 
Title > Title 
Internet EMail Address > Email 
Telephone Number > WorkPhone 
Facsimile Telephone Number > Fax 
mobile > WirelessPhone 
Description > Description 


The application attributes correspond to the sequence of values in the file or, 
if present, to the attributes associated with unnamed XDS <field> elements. 
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Policy Description 
Input Transform Configured on the driver object. 


If the input document is an XML document, no transformations are made. If 
the document is a delimited text file, each record is transformed into an XDS 
add element for User objects with attributes defined by the schema map. 


The user CN is formed by concatenating the values of first name and last 
name. 


Associations are defined by value the user's e-mail attribute. 
Output Transform Configured on the driver object. 


Specifies that a comma is used as the delimiter character for output files and 
that the file format is Comma Separated Values (CSV). 


Create Configured on the Publisher channel. 


Specifies that in order for a User to be created in eDirectory, the Given Name 
and Internet EMail Address attributes must be defined. 


Matching Configured on the Publisher channel. 


Specifies that a user in eDirectory is the same user specified in the input file 
when the value of Internet Email Address is the same in both places. 


In the case of a match, only changed attributes are updated in eDirectory. 


Placement Configured on the Publisher channel. 


Specifies that a new user is placed in the Users\Active container and named 
with the CN created by the Input Transform rule. 


You need to create a Users\Active container at the root of your tree before you 
start the driver. 


Event Transform Configured on the Subscriber channel. 


If eDirectory reports a Modify or Sync event, those events are changed to an 
instance element that can be used to create a complete output record. 


Supported File Types 


The sample configuration currently supports two types of files: 
+ Comma-Separated Values Files 


XML Files in XDS Format 


Comma-Separated Values Files 


Comma-separated values (CSV) files are text files that contain data divided into fields and records. 
Fields are delimited by commas, and records are delimited by a hard return. 


If you need a comma or hard return within the value of a particular field, the entire field value 
should be enclosed in quotes. 


Because the meaning of each field in a CSV file is derived from its position, each record ina CSV 
file should have the same number of fields. Field values can be left blank, but each record should 
have the same number of delimiter characters. 
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XML Files in XDS Format 


XDS format is the defined Novell subset of possible XML formats. This is the initial format for 
data coming from eDirectory. By modifying default rules and changing the style sheets, the 
Delimited Text driver could be configured to work with any XML format. 


For detailed information on XDS format, refer to NDS DTD Commands and Events (http:// 
developer.novell.com/ndk/doc/dirxml/index.html?dirxmlbk/data/a5323rs.html). 


For information on configuring the driver to use XML files in the XDS format, refer to 
“Configuring for XDS XML Files” on page 36. 
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Installing the DirXML Driver for Delimited Text 


This section provides information on the following: 
+ "Where to Install the Driver” on page 15 
+ "Prerequisites” on page 15 
+ “Installing the Driver” on page 15 


+ “Setting Up the Driver” on page 21 


Where to Install the Driver 


A DirXML? Driver for Delimited Text can be installed on the same computer where Novell? 
eDirectory™ and the DirXML engine are installed. This installation is referred to as a local 
configuration. If platform or policy constraints make a local configuration difficult or impossible, 
you can install the driver on the computer hosting the target application. This installation is 
referred to as a remote configuration. 


Unless you extend this driver’s functionality with the new Java interfaces, it is capable of only 
reading input files from the local file system of the computer where the driver is running. 


Prerequisites 


U Novell Nsure™ Identity Manager 2 


Installing the Driver 


You can install the Driver for Delimited Text (along with other DirXML drivers) at the same time 
that the DirXML engine is installed. See “Installation” in the Novell Nsure Identity Manager 2 
Administration Guide. 


As the following sections explain, you can also install the driver separately, after the Dir XML 
engine is installed. 


Installing to Windows 
1 Run the installation program from the Identity Manager 2.0 CD or the download image. 
If the installation program doesn’t autolaunch, you can run \nt\install.exe. 
2 In the Welcome dialog box, click Next, then accept the license agreement. 
3 In the first Dir XML Overview dialog box, review information, then click Next. 


The dialog box provides information on the following: 
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+ A DirXML server 
* A DirXML connected server system 
4 In the second DirXML Overview dialog box, review information, then click Next. 
The dialog box provides information on the following: 
+ A Web-based administration server 
¢ DirXML utilities 


5 In the Please Select the Components to Install dialog box, select only DirXML Server, then 
click Next. 


EN pirxmL install | 
Novell. 


DirXML™ 


Please select the components to install: 


RI 


DirXML Server 


G DirXML Web Components 


[ Utilities 
Description 
Installs utilities and system components for your connected Select All 
systems. 
Clear All 
| Cancel | | Help | | < Back | | Next > | 


6 In the Select Drivers for Engine Install dialog box, select only Delimited Text, then click Next. 


lol 
Novell. 


INES Drivers for Engine Install 


DirXML™ 


Please select the components to install: 
rDirXML Engine - 


O DirXML Engine 


DirXML Drivers 
O NT Domain 
= TT eDirectory 
| Active Dire) 
rn |] Lotus Notes 
|] eDirectory a 
jni | | Exchange 
|_| Lotus Note høj 
= _] LDAP 
Exchange 
ag | | GroupWise 
Description 
[V] Delimited Text 
[C] PeopleSoft 
(J spec 
[C] sap 
| Cancel || Help | | < Back || Next > | | 


You can’t deselect DirXML Schema, which is dimmed. Later, the installation program will 
extend the schema to enable the newly installed driver to function. 
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7 In the DirXML Upgrade Warning dialog box, click OK. 


8 In the Schema Extension dialog box, type a username and password, then click Next. 


9 In the Summary dialog box, review the selected options, then click Finish. 


10 In the Installation Complete dialog box, click Close. 


After installation you must configure the driver as explained in “Setting Up the Driver” on 
page 21. 


Installing to NetWare 


1 At the NetWare? server, insert the Identity Manager 2.0 CD and mount the CD as a volume. 


To mount the CD, enter m cdrom. 


2 (Conditional) If the graphical utility isn’t loaded, load it by entering startx. 


3 In the graphical utility, click the Novell icon, then click Install. 
4 In the Installed Products dialog box, click Add. 


5 In the Source Path dialog box, browse to and select the product.ni file. 


5a Browse to and expand the CD volume (NSURE IDM 2) that you mounted earlier. 


E) Source Path : 


ifle:sNSUR E_IDM_2:\nwiproduct. ni 


Gr (J cC: 
Q SJ NSURE IDM 2: 


œ [3 aix 
© hpux 
© license 
© [ linux 
o qn 
° 
© [3 dirxml 
© [ install 
o readme 
© [3 mr moved 
o- solaris 


© [y svs: 


Description 


OK | Cancel | 


5b Expand the nw directory, select product.ni, then click OK twice. 


6 In the Welcome dialog box, click Next, then accept the license agreement. 


7 In the DirXML Install dialog box, select only DirXML Server, then click Next. 


Deselect the following: 


+ 


+ 


DirXML Web Components 
Utilities 
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8 In the Select Drivers for Engine Install dialog box, select only Delimited Text. 
Deselect the following: 
* DirXML Engine 
+ All drivers except Delimited Text 
9 In the DirXML Upgrade Warning dialog box, click OK. 
The dialog box advises you to activate a license for the driver within 90 days. 
10 In the Schema Extension dialog box, type a username and password, then click Next. 
11 In the Summary page, review the selected options, then click Finish. 
12 Click Close. 


After installation you must configure the driver as explained in “Setting Up the Driver” on 
page 21. 


Installing to Linux or Solaris 


By default, the DirXML Driver for Delimited Text is installed when you install the DirXML 
engine. In case the driver wasn't installed at that time, this section can help you install it. 


As you move through the installation program, you can return to a previous section (screen) by 
entering previous. 


1 In a terminal session, log in as root. 
2 Insert the Identity Manager 2.0 CD and mount it. 


Typically, the CD is automatically mounted. To manually mount the CD: 


Platform What to Type 

Red Hat* mount /mnt/cdrom, then press Enter 
SUSE® mount /media/cdrom, then press Enter 
Solaris* mount /cdrom, then press Enter 


3 Change to the setup directory. 


Platform Path 

Red Hat /mnt/cdrom/linux/setup/ 

SUSE /media/cdrom/linux/setup/ 

Solaris /cdrom/solaris/nsure_idm_2/setup/ 
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File Edit Settinas Help 


xml linus,bin 


archive... 


L z ces from the installer archive... 
installer for t ystem's environment... 


4 Run the installation program by typing ./dirxm1_linux.bin. 
5 In the Introduction section, press Enter. 


6 Accept the license agreement. 


Press Enter until you reach the Do You Accept the Terms of This License Agreement prompt, 


type y, then press Enter. 


File Edit ila Help 


aplication 


outh Novell Place 


ENTER> TO CONTINUE: 


vention of Contracts for the 
‘is E C 


2000-2003 Novell, Inc, All Rights Reserved, 


istered tr k and eDirectory and Nsur trademarks of 


ic. in the Unite tes and other countries 


7 In the Choose Install Set section, select the Customize option. 


Type 4, then press Enter. 
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File Edit Settings Help 


nstall Set to be installed by this 


4- Customize... 


ENTER THE NUMBER FOR THE INSTALL SET, OR PRESS <ENTER 


4 


TO ACCEPT THE DEFAULT 


8 Atthe Choose Product Features section, deselect all features except Delimited Text, then press 


Enter. 


To deselect a feature, type its number. Type a comma between additional features that you 


deselect. 


File Edit Settings Help 


ENTER A COMMA SEPARATED LIST OF NUMBERS REPRESENTING THE FEATURES YOU WOULD 
LIKE TO SELECT, OR DESELECT, TO VIEW A FEATURE "S DESCRIPTION, ENTER 


'?<NUMBER ‘ RETURN> WHEN YOU ARE DONE: 


JDBC 
irectory 
SAP 
Delimited Text 


ne Features to be installed by this installer, 


9 In the Pre-Installation Summary section, review options. 
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File Edit Settings Help 


Please Review the Following Before Continuing: 


Product Name: 
M 


Install Set 
Custom 


PRESS <ENTER> TO CONTINUE: 


To return to a previous section, type previous, then press Enter. 
To continue, press Enter. 


10 After the installation is complete, exit the installation by pressing Enter. 


After installation you must configure the driver as explained in “Setting Up the Driver” on 
page 21. 


Setting Up the Driver 


If you are upgrading an existing driver, setup is not required. 


If this is the first time the Delimited Text driver has been used, complete the post-installation tasks 
in the following sections: 


+ "Configuring the Driver” on page 21 

+ "Preparing Data Locations” on page 23 

+ “Starting the Driver” on page 23 

+ “Migrating and Resynchronizing Data” on page 23 


+ “Activating the Driver” on page 25 


Configuring the Driver 


In ¡Manager, complete the following steps: 
4 Select DirXML Utilities > Create Driver. 
2 Select a driver set. 


If you place this driver in a new driver set, you must specify a driver set name, context, and 
associated server. 


3 Mark Import a Preconfigured Driver from the Server and select the 
DelimitedTextCSVSample.xml file. 


The driver configuration file is installed on the Web server when you set up ¡Manager. 


4 Click Next. 
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You are prompted for the following information: 


Field 
Driver Name 


Container 


Output File Path 


Output File Extension 


Input File Path 


Input File Extension 


Rename File Extension 


New User Container 


Configure Data Flow 


Install Driver as Remote/ 
Local 


Remote Host Name and 


Port 


Driver Password 


Remote Password 


Description 
The eDirectory object name to be assigned to this driver. 


The container in eDirectory where new users should be created. 


If this container doesn't exist, you must create it before you start the 
driver. 


Specify the platform-specific path to the local directory where output 
files should be created. (For example, on Windows the path is 
cicsvsampleloutput.) 


Specify the extension to append to output files when those files are 
created. 


Specify the platform-specific path to the local directory where input 
files exist. 


Specify the extension used to designate input files. 


Specify the extension that an input file will be renamed with after the 
file has been processed. Leave this field blank if you want the file 
deleted. 


Specify the DN of the container where new users are to be placed. 


You can configure dataflow to one of the following options: 


+ Bidirectional: Delimited Text and eDirectory are both 
authoritative sources of the data synchronized between them. 


+ DT-to-eDirectory: Delimited Text is the authoritative source. 


+ eDirectory-to-DT: eDirectory is the authoritative source. 


Configure the driver for use with the Remote Loader service by 
selecting the Remote option, or select Local to configure the driver 
for local use. If you select Local, you can skip the remaining 
parameters. 


Specify the host name or IP address and port number for where the 
Remote Loader service has been installed and is running for this 
driver. The default port is 8090. 


The driver object password is used by the Remote Loader to 
authenticate itself to the DirXML server. It must be the same 
password that is specified as the driver object password on the 
DirXML Remote Loader. 


The Remote Loader password is used to control access to the 
Remote Loader instance. It must be the same password that is 
specified as the Remote Loader password on the DirXML Remote 
Loader. 


5 Click Finish. 


NOTE: You can configure and modify the driver's other parameters. For more information, referto “Configuring 
Driver Parameters” on page 29. 
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Preparing Data Locations 


If you use all of the defaults provided by the sample configuration, prepare locations for DirXML 
data:. 


1 Add the containers Users\Active at the root level of your eDirectory tree. 

2 On Windows, create the following two directories on your local file system: 
+  cicvsamplelinput 
*  cicvsampleloutput 


On Solaris, Linux, or Net Ware, create input and output directories wherever you'd like. Then 
update the driver configuration with the correct platform-specific paths. For more 
information, refer to Source File Path in the Publisher Settings section. (See “Publisher 
Settings” on page 34). 


Starting the Driver 


If you changed default data locations during configuration, ensure that the new locations exist 
before you start the driver. 


1 In iManager, select DirXML Management > Overview. 
2 Locate the driver in its driver set. 


3 Click the driver status indicator in the upper right corner of the driver icon, then click Start 
Driver. 


Synchronization takes place on an object-by-object basis as changes are made to individual 
objects. If you want to have an immediate synchronization, you must initiate that process as 
explained in “Migrating and Resynchronizing Data” on page 23. 


Migrating and Resynchronizing Data 


Identity Manager synchronizes data as the data changes. If you want to synchronize all data 
immediately, you can do one of the following; 


+ Migrate new data into or from eDirectory. 


+ Resynchronize existing data by using the driver set Properties page. 


The Migrate from eDirectory and Synchronize options usually behave independently of any driver. 
However, some issues exist with these options and the DirXML Driver for Delimited Text. 


The following figure illustrates the buttons that select the Migrate from eDirectory and 
Synchronize options: 
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DirXML Driver Overview 


Driver: Delimited Text.Driverset1.vmp 


Export... — | Migrate from eDirectory...| Migrate into eDirectory... | 


Synchronize 


Migrating Data from eDirectory 


To find eDirectory entries that do not have a DirXML association for the driver, click Migrate from 
eDirectory. Non-associated entries that are not vetoed by rules processing are written to the output 
file and will receive an association. 


NOTE: Entries that already have up-to-date associations aren't written to the output file. To output all 
associated entries, click Synchronize. 


Migrating Data into eDirectory 


Synchronizing Data 
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With most DirXML drivers, migrating into eDirectory causes the DirXML engine to query the 
application through its driver. The query finds entries that can be synchronized from the 
application into eDirectory. These synchronized entries are created in eDirectory. The driver 
assigns an association value to each new entry. 


The Migrate into eDirectory option has no function when used with the DirXML Driver for 
Delimited Text. This driver gets all of its input as files are placed in the input directory. Because 
the driver is always up-to-date concerning the files it processes, you don’t need to do any 
additional processing or querying. If you do click Migrate into eDirectory, nothing happens 
because queries are disabled with this driver. 


When entries in eDirectory have an association with the selected driver, the Synchronize option 
causes those entries to synchronize again with the associated entries in the application. Ifthe driver 
has a Subscriber channel, eDirectory is considered to be the authoritative source for the attributes 
in the Subscriber filter. 


The DirXML Driver for Delimited Text can't query the application directly to determine what is 
out of sync. Therefore, the DirXML engine sends a Modify event to the driver for each associated 
entry. This event causes each of these entries to be written to an output file whenever you click 
Synchronize. If no Subscriber is configured, Synchronize will have no effect with the driver. 
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To use Migrating from eDirectory, Migrating into eDirectory, or Synchronize: 
1 In iManager, select Dir XML Management > Overview. 
2 Locate the driver set containing the Delimited Text driver, then double-click the driver icon. 


3 Click the appropriate migration button. 


Activating the Driver 
Activate the driver within 90 days of installation. Otherwise, the driver will stop working. 


For information on activation, refer to “Activating Novell Identity Manager Products” in the 
Novell Nsure Identity Manager 2 Administration Guide. 
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Upgrading the DirXML Driver for Delimited Text 


You can upgrade the DirXML? Driver for Delimited Text at the same time that you install the 
engine or you can upgrade after the engine is installed. 


To upgrade your DirXML Driver for Delimited Text after the engine is installed: 


1 Run the Identity Manager 2 installation program from the Identity Manager 2.0 CD or 
download image. 


For Windows” NT*, refer to “Installing to Windows” on page 15. 

For NetWare®, refer to “Installing to NetWare” on page 17. 

For Solaris” or Linux”, refer to “Installing to Linux or Solaris” on page 18. 
2 Select the DirXML Driver for Delimited Text. 


The new driver replaces the previous driver. Because your previous driver configuration is 
preserved, no post-installation configuration is required. 


3 Restart the driver. 


IMPORTANT: The sample configuration file for the updated driver has changed for this release of Identity 
Manager. If your current configuration meets your requirements, you don’t need to import this sample 
configuration. If you do import the new sample configuration, you will see an additional driver for Delimited Text 
with a new name, a new eDirectory container specified in the placement rule, and new rule names. 
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Configuring 


Customizing the DirXML Driver for Delimited 
Text 


The DirXML? Driver for Delimited Text includes a sample configuration that you can use as a 
starting point for your deployment. 


Most deployments require you to change the sample configuration. For example, if you need only 
one-way data synchronization, or if the attributes you're synchronizing are different from the eight 
provided in the sample, you need to customize the driver. 


This section covers the following customization topics: 
+ "Configuring Driver Parameters” on page 29 
+ "Configuring Data Synchronization” on page 37 
+ “Using Java Interfaces to Customize File Processing” on page 38 


NOTE: When you customize data synchronization, you must work within the supported standards and 
conventions for the operating systems and accounts being synchronized. Data containing characters that are 
valid in one environment, but invalid in another, causes errors. 


Driver Parameters 


When you change driver parameters, you tune driver behavior to align with your network 
environment. For example, you might find the default publisher polling interval to be shorter than 
your synchronization requires. Making the interval longer could improve network performance 
while still maintaining appropriate synchronization. 


Driver parameters are divided into the following settings: 
+ Driver (See “Driver Settings” on page 31.) 
+ Subscriber (See “Subscriber Settings” on page 32.) 
+ Publisher (See “Publisher Settings” on page 34.) 
To configure the driver parameters: 
1 In iManager, select DirXML Management > Overview. 
2 Using the Find, Browse, or Search feature, locate the DirXML Driver for Delimited Text set. 


The following figure illustrates using the Search feature. 
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DirXML Overview 


DirXML Overview searches Novell eDirectory and displays Driver Sets found 
in the directory, To minimize the search time, Novell advises placing all 
DirXML-DriverSet objects in a common container in the tree. 


Where do you want to search for the Driver Sets? 


© Search entire tree 
@ Search in container: 


[delimited] RE 
Search | Cancel | 
3 View the driver overview by clicking the driver icon (Delimited Text). 


DirXML Overview 


1 Driver Set(s) found in: Entire directory 


Driver Set: Driverset1.novell 


Delimited Text 


4 Access the Driver Configuration page by clicking the driver icon again. 


DirXML Driver Overview 


Driver: Delimited Text.Driverset1.vmp 
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5 Scroll to the Driver Parameters section, make changes, then click OK. 


Driver Parameters 


BFI011-NDS.vmp 


Edit XML 


Driver Settings 


To make changes to the Driver Settings section, see “Driver Settings” on page 31. 
To make changes to the Subscriber Settings section, see “Subscriber Settings” on page 32. 


To make changes to the Publisher Settings section, see “Publisher Settings” on page 34. 


Driver Settings 


The following figure illustrates the driver settings and their default values in the sample 
configuration. 


Driver Parameters 


BFIO11-NDS.vmp 


Edit XML 


Driver Settings 


Field Delimiter: l 


Field Names (Field1, Field2, Field3...): LastName FirstName Title Email WWYorkF 


Object Class Name: [User 
Allow Driver to Consume lts Own Output? [no 


Field Delimiter 


Field Delimiter indicates the character that is used to delimit field values in the input files. It must 
be one character. 


If the values of any of the input fields contain this character, enclose the entire value in quotes to 
prevent it from being seen as a delimiter. 

NOTE: Changing this delimiter parameter to something other than a comma does not automatically change 
the delimiter character used in the output files when a Subscriber is used. To change the delimiter character 
in the output files, edit the Output Transform style sheet. The delimiter character is assigned to a variable near 
the top of that style sheet. 


Field Names 


Field Names is a comma-separated list of attribute names that can be referred to in the Schema 
Mapping rule. In the input files, the fields of the records must correspond to the order and 
positioning of the names in this list. 


For example, if you list eight field names in this parameter, each record of the input files should 
have eight fields separated by the field delimiter character. On NetWare® and Windows, see 
sample.csv in the delimitedtext/samples directory for an example. On Solaris and Linux, 
sample.csv is located in the /usr/lib/dirxml/rules/delim directory. 
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The following table lists the default values: 


Parameter Sample Configuration Value 


Field Names (Field 1, Field 2, Field 3...) LastName,FirstName, Title, Email, VorkPhone, Fax, 
WirelessPhone, Description 


Object Class Name 

Object Class Name is the Novell® eDirectory™ class name that should be used when creating new 
objects to correspond to input files. 

Allow Driver to Consume Its Own Output 


This parameter prevents you from inadvertently creating a situation in which the driver writes 
output files that are immediately read in again as input of the same driver. 


The default is No. By default, the driver won’t load if all the following conditions occur: 
+ You have both a Subscriber channel and a Publisher channel. 
¢ The input and output directories are the same. 
¢ The input and output file extensions are the same. 


If you want to feed the output of the Subscriber channel into the input of the Subscriber channel 
as a way to detect eDirectory events to trigger other changes in eDirectory, set this parameter to 

Yes. For example, if you want the Full Name attribute updated when the Given Name, Surname, 
or Initials attributes are updated, set this parameter to Yes. 


Subscriber Settings 
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The following figure illustrates the Subscriber settings and their default values in the sample 
configuration. 


Subscriber Settings 
Output File Path: [c\csvsample\output ==” 
Output File Extension: .CSV 
Destination File Character Encoding (leave blank for default): A 


Maximum Number of Transactions per Output File: 


Maximum Time in Seconds before Flushing All Transactions: 20 
Time of Day (Local Time) to Flush All Transactions: | 


Output File Path 


Output File Path is the directory on the local file system where output files will be created. An error 
occurs if this directory doesn't exist. 


Platform Sample Configuration Value 


Windows c:\csvsample\output 
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Platform Sample Configuration Value 


Solaris or Linux /csvsample/output 


NetWare Specify the volume (for example, sys:csvsample\output) 


Output File Extension 


Output files have a unique name that ends with the characters in the Destination File Extension 
parameter. If the output files from a Subscriber are used as input files for the Publisher of another 
Delimited Text DirXML Driver, the destination file extension must match the source file extension 
parameter of the second driver. 


Destination File Character Encoding 


When the Destination File Character Encoding parameter contains no value, the default Java 
character encoding for your locale are used. 


To use an encoding other than the default for your locale, enter one of the canonical names from 
the Supported Encodings table (http://java.sun.com/j2se/1.4.2/docs/guide/intl/ 
encoding.doc.html). 


NOTE: The Publisher and Subscriber can use different character encodings. 


Maximum Number of Transactions Per Output File 


This parameter determines the maximum number of transactions that are written to a single output 
file. When the file transaction limit is reached, the file closes, and a new file is created for 
subsequent transactions. If you don’t want to limit the number of transactions that can be written 
to a single file, leave this parameter blank or set it to zero. For more information, refer to Maximum 
Time in Seconds Before Flushing All Transactions. 


Maximum Time in Seconds Before Flushing All Transactions 


If no new transactions have been written to the output file in the amount of time specified in this 
parameter, the file is closed. When new transactions need to be written, a new output file is created. 
If you don't want to limit the time that can pass before the output file is closed, leave this parameter 
blank or set it to zero. 


Time of Day (Local Time) to Flush All Transactions 


If a value is supplied for this parameter, the current output file is closed at the specified time each 
day. Subsequent transactions are written to a new file. This parameter does not prevent the 
Maximum Number of Transactions or the Maximum Time in Seconds parameters from also acting 
as output file thresholds. If you use this parameter and only want one file per day, set the other two 
parameters to zero. 


The format of this parameter can be HH:MM:SS (using the 24-hour clock) or H:MM:SS AM/PM. 
An hour is required, but the minutes and seconds are optional. Because the parameter assumes 
local time, any time zone information included in the value is ignored. 

NOTE: The previous three parameters (Maximum Number of Transactions Per Output File, Maximum Time in 
Seconds Before Flushing All Transactions, Time of Day to Flush All Transactions) are all capable of acting as 


a threshold for the transaction size a file is able to grow to, or for the time that it will remain open to accept new 
transactions. 


As long as an output file is still open for writing by the Delimited Text driver, it shouldn’t be considered as 
finalized, and you should avoid opening the file in any other process until the driver closes it. For this reason, 
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one of the three previous parameters must be set to assure that output files don't remain open indefinitely. To 
avoid this condition, if the driver detects that all three parameters are blank (or zero) it automatically sets the 
Maximum Number of Transactions per Output File to the value of 1. 


Publisher Settings 
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The following table lists the Publisher settings and their default values in the sample configuration. 


Parameter Sample Configuration Value 
Source File Path On Windows: c:\csvsample\input 
On Solaris and Linux: /usr/lib/dirxml/rules/delim 


For NetWare, you need to specify the volume (for 
example, sys:csvsamplelinput) 


Source File Extension .CSV 


Source File Character Encoding (leave [blank] 
blank for default) 


Source File Rename Extension (leave blank bak 
to delete a file) 


Polling Rate (in seconds) 10 


Source File Path 


The Publisher looks for new input files in the Source File Path, which is a directory on the local 
file system. 


Source File Extension 


The Publisher uses only files that have the extension specified in this parameter. After the files 
have been processed, the value of the Source File Rename Extension parameter is appended to the 
filename, so the Publisher won't try to process the same file again. If the value of the Source File 
Rename Extension parameter is left blank, the source file is deleted after it is processed. 


Source File Character Encoding 


When the Source File Character Encoding parameter contains no value, the default Java character 
encoding for your locale is used. 


To use an encoding other than the default for your locale, enter one of the canonical names from 
the Supported Encodings table (http://java.sun.com/j2se/1.4.2/docs/guide/intl/ 
encoding.doc.html). 


If the Source File Extension parameter is .xml, the Source File Character Encoding can be 
indicated in one of two ways: 


¢ Ifa value is indicated in the Source File Character Encoding parameter, it is used. 


¢ Ifthe parameter is blank, and if the XML document specifies an Encoding Declaration as 
described in the W3C XML Recommendation (http://www.w3.org/TR/REC- 
xml#charencoding) in paragraph 4.3.3, the Encoding Declaration is handled by the XML 
parser in the DirXML engine. 


The DirXML XML parser handles the following character encodings: 
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+ UTF-8 

+ UTF-16 

+ ISO-8859-1 
+ US-ASCII 


NOTE: The Publisher and Subscriber can use different character encodings. 


Source File Rename Extension 


For information on Source File Rename Extension, see Source File Extension in this section 
(“Publisher Settings” on page 34). 


IMPORTANT: If you change the default, use only characters that are valid in filenames on your platform. 
Invalid characters cause the rename to fail and the driver to reprocess the same file repeatedly. 


Polling Rate 


When the Publisher has finished processing all source files, it waits the number of seconds 
specified in this parameter before checking for new source files to process. 


Setting Up One-Way Synchronization 


If your data synchronization goes only one way, disable the channel that you won't use. To disable 
one of the channels, clear the filters on the channel you don’t need and don’t specify a path for the 
input or output directory, depending on the channel. 


For example, if you only need a Publisher channel: 
1 On the Filter editor in iManager, clear the filters on the Subscriber object. 


da For example, select the Given Name filter. 


Server Variables \ Other 


Driver Configuration | Global Config Values | N 
Security Equals | Filter | Edit Filter XML | Misc 


Add Class | Add Attribute | Delete | Copy Fi 
Filter 
E ED User 
ED Description 
> Facsimile Telephone Number 


ED Given Name 


ED Internet EMail Address 


1b Select Ignore in the Subscribe section. 
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Application Name: 
FirstName 


Publish: 
Ge Synchronize 
C Ignore 
% © Notify 


Subscribe: 
© Synchronize 
Be Ignore 
% © Notify 


As the following figure illustrates, the filter’s Subscribe channel is disabled. 


Gb Given Name 


2 Save the changes by clicking OK. 


3 In the Driver Parameters section, scroll to Subscriber Settings and remove the path specified 
for the Output File Path. 


Subscriber Settings 


Output File Path: | 


Output File Extension: CSV 


If you only need a Subscriber channel, clear the filters on the Publisher object and remove the path 
specified for the Source File Path in the Driver Parameters section. 


Configuring for XDS XML Files 


You can use XML files in XDS format instead of comma-separated value (CSV) files with the 
driver. 


Because you generally will want to use this driver only with a Publisher or Subscriber channel, 
perform only the steps from the section that you need. 


Using the Publisher Channel 


To have the driver accept input in XML format, change the input file extension to .xml. 


Using the Subscriber Channel 


To have the driver send output in XDS format, remove the Event Transform and Output Transform 
style sheets from the Subscriber channel. 


1 In iManager, select eDirectory Administration > Delete Object. 

2 Browse to and select the SubscriberEventTransformSS object for the driver. 
3 Click OK. 

4 Click Repeat Task. 
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5 Browse to and select the OutputTransformSS object for the driver. 


6 Click OK twice. 


Configuring Data Synchronization 


The real power of Nsure™ Identity Manager is in managing the shared data itself. This section 
covers some common customizations for the DirXML Driver for Delimited Text. 


The sample configuration available with the driver uses comma-separated value files. However, 
you can use the driver in many ways. It is designed to be as flexible as possible. The driver passes 
the text-based files largely unchanged to the style sheets. The style sheets do most ofthe work. You 
can write new style sheets that will allow the driver to work with almost any text-based file that 
contains predictably repeatable patterns. 


The basis for this exchange is the <delimited-text> XML element. For example, to design a 
Publisher that reads information from a text file, create an Input Transform style sheet that receives 
the contents of the file and converts it into a <delimited-text> element. 


The following is an example of a <delimited-text> element: 


<delimited-text> 
<record> 
<field>John</field> 
<field>Maxfield</field> 
<field>555-1212</field> 
</record> 
<record> 
<field>Sarah</field> 
<field>Lopez</field> 
<field>555-3434</field> 
</record> 
</delimited-text> 


When field elements appear like this without an identifying name attribute, the driver uses the field 
position and matches it with the position of the Field Name driver parameter. 


You can provide the field name within the XML: 


<delimited-text> 
<record> 
<field name="FirstName">John</field> 
<field name="LastName">Maxfield</field> 
<field name="Phone">555-1212</field> 
</record> 
<record> 
<field name="FirstName">Sarah</field> 
<field name="LastName">Lopez</field> 
<field name="Phone">555-3434</field> 
</record> 
</delimited-text> 


For detailed information on writing style sheets to handle other document types, refer to the sample 
style sheets that come with this driver. If you create the driver using the sample configuration, you 
will find Input Transform, Output Transform, and Event Transformation style sheets that you can 
use as a Starting point. 
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Using Java Interfaces to Customize File Processing 


Java interfaces enable you to customize file processing by using Java classes that you write. These 
interfaces are InputSorter, InputSource, PreProcessor, and PostProcessor. 


These enhancements to the driver require Java programming. To implement this functionality, 
complete the following processes: 


+ Create a Java class that implements one of the new interfaces. 
+ Create a Java .jar file that contains your new class. 


+ Configure the driver to use the new class. 


Creating a New Java Class 


JavaDoc and a sample class are included with the driver to help you implement this new 
functionality. Find these files at platform\dirxml\drivers\delimitedtext\extensions. 


Creating a Java .jar File 


After you have implemented your class file, create a Java .jar file (Java archive) using the jar tool. 
The .jar file must contain the class that you have created. Put the .jar file into the novell/nds/lib 
directory. The path might differ, depending on the platform you're on, but it should be the same 
location as the DelimitedTextShim.jar and the DelimitedTextUtil.jar. 


Configuring the Driver to Use the New Class 


After you have placed the new .jar file in the correct location, configure the driver to use your new 
class by modifying the driver’s properties. 


1 In iManager, select DirXML Management > Overview. 
Locate the driver in its driver set. 

Click the driver icon to open the Driver Overview Page. 
Click the driver icon again to open the Modify Object page. 


Click Driver Configuration > Driver Parameters > Edit XML. 


og AO N 


Locate the <publisher-options> section of the file. 


This file defines which parameters and values appear in the Driver Parameters section of the 
Driver Configuration page. 


For each class you created that works on the Publisher channel, you will enter an additional 
option in the <publisher-options> section. After you've updated this file, you’ll see your new 
options in the interface. 


7 For each new class you created on the publisher channel, add an entry corresponding to the 
interface type. Use the following table as a guide: 
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Interface New Entry 


InputSorter <input-sorter display-name="InputSorter Class">com.acme.MyNewClass</ 
input-sorter> 


<input-sorter-params display-name="InputSorter init string">MY CONFIG 
PARAMS</input-sorter-params> 


InputSource <input-source display-name="InputSource Class">com.acme.MyNewClass</ 
input-source> 


<input-source-params display-name="InputSource init string">MY CONFIG 
PARAMS</input-source-params> 


PreProcessor <pre-processor display-name="PreProcessor 
Class">com.acme.MyNewClass</pre-processor> 


<pre-processor-params display-name="PreProcessor init string">MY CONFIG 
PARAMS</pre-processor-params> 


7a Replace com.acme.MyNewClass with the name of the class that you have defined along 
with a full package identifier. 


7b Replace MY CONFIG PARAMS with any information that you want to pass to the init 
method of your class. 


The init method of your class is then responsible for parsing the information contained in 
this string. If your class doesn't require a configuration string to be passed to the init 
method, you can leave off the whole element, in which case null would be passed to the 
init method. 


8 Ifyou created a PostProcessor rule, locate the <subscriber-options> section ofthe file and add 
the following lines: 


<post-processor display-name="PostProcessor Class">com.acme.MyNewClass</ 
post-processor> 


<post-processor-params display-name="PostProcessor init string">MY CONFIG 
PARAMS< /post-processor-params> 


8a Replace com.acme.MyNewClass with the name of the class that you have defined along 
with full package information. 


8b Replace MY CONFIG PARAMS with any information that you want to pass to the init 
method of your class. 


The init method of your class is then responsible for parsing the information contained in 
this string. If your class doesn't require a configuration string to be passed to the init 
method, you can leave off the entire element, in which case null would be passed to the 
init method. 


9 Click OK. 
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Documentation Updates 


This section contains new or updated information on the DirXML® Driver for Delimited Text. 


The documentation is provided on the Web in two formats: HTML and PDF. The HTML and PDF 
documentation are both kept up-to-date with the documentation changes listed in this section. 


If you need to know whether a copy of the PDF documentation you are using is the most recent, 
check the date that the PDF file was published. The date is in the Legal Notices section, which 
immediately follows the title page. 


New or updated documentation was published on the following dates: 


+ “August 3, 2004” on page 41 


August 3, 2004 


The following updates were made in this section: 


Location Change 


Chapter 1, “Introducing the Deleted general information that applies to and is found in the 
DirXML Driver for Delimited Administration Guide but doesn’t apply to the DirXML Driver for Delimited 
Text,” on page 9 Text. 


Chapter 2, “Installing the Provided installation steps by platform (Windows, Linux or Solaris, and 
DirXML Driver for Delimited NetWare®). 
Text,” on page 15 


Chapters 2 and 3 Added graphics concerning the interface and configuration settings. 
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